Add some HTML docs for pkgid specs

diff --git a/Makefile.in b/Makefile.in
index 24005dc076ea9ccc6b724e948c5a93d5ebb02427..066d282758491e8a2b3bff363b1e4d3d0ffc7ad2 100644 (file)
--- a/Makefile.in
+++ b/Makefile.in
@@ -102,7 +102,7 @@ clean:
 
 # === Documentation
 
-DOCS := index faq config guide manifest native-build
+DOCS := index faq config guide manifest native-build pkgid-spec
 DOC_DIR := target/doc
 DOC_OPTS := --markdown-no-toc \
                --markdown-css stylesheets/normalize.css \

diff --git a/src/bin/pkgid.rs b/src/bin/pkgid.rs
index 48e4b6636e700d109dea86d9fd8c754601175f00..495501f6be6f4ac51d421e5eedf73ab5629feeec 100644 (file)
--- a/src/bin/pkgid.rs
+++ b/src/bin/pkgid.rs
@@ -16,9 +16,9 @@ Options:
     --manifest-path PATH    Path to the manifest to the package to clean
     -v, --verbose           Use verbose output
 
-Given a <pkgid> argument, print out the fully qualified package id specifier.
-This command will generate an error if <pkgid> is ambiguous as to which package
-it refers to in the dependency graph. If no <pkgid> is given, then the pkgid for
+Given a <spec> argument, print out the fully qualified package id specifier.
+This command will generate an error if <spec> is ambiguous as to which package
+it refers to in the dependency graph. If no <spec> is given, then the pkgid for
 the local package is printed.
 
 This command requires that a lockfile is available and dependencies have been

diff --git a/src/cargo/ops/cargo_generate_lockfile.rs b/src/cargo/ops/cargo_generate_lockfile.rs
index fbc65c9d3613e7d80226ce79a983707e911d1d85..05dac10b31a19165afe5664f7f3215ad049cc7b4 100644 (file)
--- a/src/cargo/ops/cargo_generate_lockfile.rs
+++ b/src/cargo/ops/cargo_generate_lockfile.rs
@@ -54,7 +54,6 @@ pub fn update_lockfile(manifest_path: &Path,
         Some(name) => {
             let mut to_avoid = HashSet::new();
             let dep = try!(resolve.query(name.as_slice()));
-            fill_with_deps(&resolve, dep, &mut to_avoid);
             if aggressive {
                 fill_with_deps(&resolve, dep, &mut to_avoid);
             } else {

diff --git a/src/doc/guide.md b/src/doc/guide.md
index 107fbb6d5e9f3afb2e195dcc3cf1e88c00129bb3..327820aaf1e987469dfbd99729aa860c280d9511 100644 (file)
--- a/src/doc/guide.md
+++ b/src/doc/guide.md
@@ -294,7 +294,10 @@ $ cargo update       # updates all dependencies
 $ cargo update color # updates just 'color'
 ```
 
-This will write out a new `Cargo.lock` with the new version information.
+This will write out a new `Cargo.lock` with the new version information. Note
+that the argument to `cargo update` is actually a
+[Package ID Specification](pkgid-spec.html) and `color` is just a short
+specification.
 
 # Overriding Dependencies
 
@@ -393,7 +396,4 @@ To test your project on Travis-CI, here is a sample `.travis.yml` file:
 
 ```
 language: rust
-script:
-  - cargo build --verbose
-  - cargo test --verbose
 ```

diff --git a/src/doc/pkgid-spec.md b/src/doc/pkgid-spec.md
new file mode 100644 (file)
index 0000000..c5e86b3
--- /dev/null
+++ b/src/doc/pkgid-spec.md
@@ -0,0 +1,44 @@
+% Package ID Specifications
+
+# Package ID Specifications
+
+Subcommands of cargo frequently need to refer to a particular package within a
+dependency graph for various operations like updating, cleaning, building etc.
+To solve this problem, cargo supports Package ID Specifications. A specification
+is a string which is used to uniquely refer to one package within a graph of
+packages.
+
+## Specification grammar
+
+The formal grammar for a Package Id Specification is:
+
+```notrust
+pkgid := pkgname
+       | [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
+pkgname := name [ ":" semver ]
+
+proto := "http" | "git" | ...
+```
+
+Here, brackets indicate that the contents are optional.
+
+## Example Specifications
+
+These could all be references to a package `foo` version `1.2.3` from the
+registry at `crates.io`
+
+|         pkgid                  |  name  |  version  |          url         |
+|-------------------------------:|:------:|:---------:|:--------------------:|
+| `foo`                          | foo    | *         | *                    |
+| `foo:1.2.3`                    | foo    | 1.2.3     | *                    |
+| `crates.io/foo`                | foo    | *         | *://crates.io/foo    |
+| `crates.io/foo#1.2.3`          | foo    | 1.2.3     | *://crates.io/foo    |
+| `crates.io/bar#foo:1.2.3`      | foo    | 1.2.3     | *://crates.io/bar    |
+| `http://crates.io/foo#1.2.3`   | foo    | 1.2.3     | http://crates.io/foo |
+
+## Brevity of Specifications
+
+The goal of this is to enable both succinct and exhausitive syntaxes for
+referring to packages in a dependency graph. Ambiguous references may refer to
+one or more packages. Most commands generate an error if more than one package
+could be referred to with the same specification.

diff --git a/src/doc/stylesheets/all.css b/src/doc/stylesheets/all.css
index 6ba7557d6b8b59c0a20b9b5a355b7ed93c1d6f18..1f4cdca651d89f92bcb819204d8a9cb2cfb90070 100644 (file)
--- a/src/doc/stylesheets/all.css
+++ b/src/doc/stylesheets/all.css
@@ -150,3 +150,6 @@ pre.rust .doccomment { color: #4D4D4C; }
 pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999F; }
 pre.rust .lifetime { color: #B76514; }
 code span.s1 { color: #2AA198; }
+
+table th { border-bottom: 1px solid black; }
+table td, table th { padding: 5px 10px; }